Alert

Alert
Header:	Dialogs.h		Carbon status:	Supported

Displays an alert box and/or plays an alert sound.

DialogItemIndex Alert (
    SInt16 alertID, 
    ModalFilterUPP modalFilter
);

alertID: The resource ID of an alert resource and extended alert resource. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert. See ‘alrx’ for a description of the extended alert resource.
modalFilter: A universal procedure pointer for a filter function that responds to events not handled by the ModalDialog function. If you set this parameter to null, the Dialog Manager uses the standard event filter function.

function result: If no alert box is to be drawn at the current alert stage or the 'ALRT' resource is not found, Alert returns –1; otherwise, it creates and displays the alert box and returns the item number of the control selected by the user; see “Alert Button Constants”.0

DISCUSSION

The Alert function displays an alert box or, if appropriate for the alert stage, plays an alert sound instead of or in addition to displaying the alert box. The Alert function creates the alert defined in the specified alert resource and its corresponding extended alert resource. The function calls the current alert sound function and passes it the sound number specified in the alert resource for the current alert stage. If no alert box is to be drawn at this stage, Alert returns –1; otherwise, it uses the NewDialog function to create and display the alert box. The default system window colors are used unless your application provides an alert color table resource with the same resource ID as the alert resource. The Alert function uses the ModalDialog function to get and handle most events for you.

The Alert function does not display a default icon in the upper-left corner of the alert box; you can leave this area blank, or you can specify your own icon in the alert’s item list resource, which in turn is specified in the alert resource.

The Alert function continues calling ModalDialog until the user selects an enabled control (typically a button), at which time the Alert function removes the alert box from the screen and returns the item number of the selected control. Your application then responds as appropriate when the user clicks this item.

Your application should never draw its own default rings. Prior to Mac OS 8, the Alert function would only redraw the default button ring once and never redraw it on an update event. However, when Appearance is available, default rings do redraw when you call Alert.

See also the functions NoteAlert, CautionAlert, and StopAlert.

SPECIAL CONSIDERATIONS

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, call AEInteractWithUser

The Dialog Manager uses the system alert sound as the error sound unless you change it by calling the ErrorSound function .

VERSION NOTES

This function was changed with Appearance Manager 1.0 to support the extended alert ('alrx') resource.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.